package org.g4studio.core.orm.xibatis.sqlmap.engine.mapping.result;

/**
 * iBATIS uses an implementation of this interface to create result objects
 * after the execution of a statement. To use, specify your implementation class
 * as the type for the "resultObjectFactory" element in the SqlMapConfig. Any
 * implementation of this interface must have a public no argument constructor.
 * 
 * Note that iBATIS makes use of this interface through the
 * ResultObjectFactoryUtil class.
 * 
 * @author Jeff Butler
 * 
 */
public interface ResultObjectFactory {

	/**
	 * Returns a new instance of the requested class. iBATIS will call this
	 * method in these circumstances:
	 * 
	 * <ul>
	 * <li>When processing a result set - to create new instances of result
	 * objects</li>
	 * <li>When processing the output parameters of a stored procedure - to
	 * create instances of OUTPUT parameters</li>
	 * <li>When processing a nested select - to create instances of parameter
	 * objects on the nested select</li>
	 * <li>When processing result maps with nested result maps. iBATIS will ask
	 * the factory to create an instance of the nested object. If the nested
	 * object is some implementation of <code>java.util.Collection</code> then
	 * iBATIS will supply default implementations of the common interfaces if
	 * the factory chooses not to create the object. If the embedded object is a
	 * <code>java.util.List</code> or <code>java.util.Collection</code> the
	 * default behavior is to create an <code>java.util.ArrayList</code>. If the
	 * embedded object is a <code>java.util.Set</code> the default behavior is
	 * to create a <code>java.util.HashSet</code>.</li>
	 * </ul>
	 * 
	 * If you return <code>null</code> from this method, iBATIS will attempt to
	 * create in instance of the class with it's normal mechanism. This means
	 * that you can selectively choose which objects to create with this
	 * interface. In the event that you choose not to create an object, iBATIS
	 * will translate some common interfaces to their common implementations. If
	 * the requested class is List or Collection iBATIS will create an
	 * ArrayList. If the requested class is Set then iBATIS will create a
	 * HashSet. But these rules only apply if you choose not to create the
	 * object. So you can use this factory to supply custom implementations of
	 * those interfaces if you so desire.
	 * 
	 * @param statementId
	 *            the ID of the statement that generated the call to this method
	 * @param clazz
	 *            the type of object to create
	 * @return a new instance of the specified class. The instance must be
	 *         castable to the specified class. If you return <code>null</code>,
	 *         iBATIS will attempt to create the instance using it's normal
	 *         mechanism.
	 * @throws InstantiationException
	 *             if the instance cannot be created. If you throw this
	 *             Exception, iBATIS will throw a runtime exception in response
	 *             and will end.
	 * @throws IllegalAccessException
	 *             if the constructor cannot be accessed. If you throw this
	 *             Exception, iBATIS will throw a runtime exception in response
	 *             and will end.
	 */
	Object createInstance(String statementId, Class clazz) throws InstantiationException, IllegalAccessException;

	/**
	 * Called for each property configured in the SqlMapCong file. All the
	 * properties will be set before any call is made to createInstance
	 * 
	 * @param name
	 * @param value
	 */
	void setProperty(String name, String value);
}
